home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / utility / 566 / capthook / capthook.txt < prev   
Text File  |  1991-12-07  |  18KB  |  385 lines
  1.                **************************************
  2.                *                                    *
  3.                *  Captain Hook 1.0                  *
  4.                *  by John Eidsvoog                  *
  5.                *  Copyright 1991 John Eidsvoog      *
  6.                *                                    *
  7.                **************************************
  8.  
  9.                Release date: Friday, December 6, 1991
  10.  
  11.  
  12.  > Captain Hook is shareware and may be distributed freely as long as
  13.  > this text file is included, but may not be sold commercially or
  14.  > included with a commercial product without written permission from
  15.  > John Eidsvoog.  Captain Hook is free to legitimate owners of MIDI
  16.  > Spy.  All other users of Captain Hook are expected to register their
  17.  > copy by sending a shareware payment to the address listed below. 
  18.  
  19.  
  20.  
  21. What it is
  22. ----------
  23.  
  24. Captain Hook "unhooks" other resident programs and accessories in order
  25. to eliminate conflicts with the programs you use.  This is especially
  26. useful with MIDI programs that seem to get overflow problems or simply
  27. don't work when some resident software is installed. 
  28.  
  29. Captain Hook's usefulness is not limited to MIDI programs, though.  It
  30. can be used to solve almost any program conflict.  For instance, if you
  31. find that a program doesn't work with a screen accelerator installed,
  32. you can probably make it work by listing that program in your
  33. CAPTHOOK.DAT file with a "2" to unhook trap 2. 
  34.  
  35. The operation of Captain Hook, by its very nature, may be a bit
  36. difficult to understand.  I fully realize that this program is going to
  37. cause a lot of confusion for those who try to use it.  Help and tips on
  38. using Captain Hook will be provided on the GEnie on-line service, in the
  39. Atari ST Roundtable's CodeHead Category 32 in the Captain Hook topic.  I
  40. will try to explain the operation of Captain Hook in this document in a
  41. way that everyone can understand it.  Even though this description is
  42. quite technical, please try to read it in its entirety to understand how
  43. Captain Hook works. 
  44.  
  45.  
  46. How to set it up
  47. ----------------
  48.  
  49. Although Captain Hook can be installed from the desktop, it is intended
  50. to be run from your AUTO folder.  If you do not already have an AUTO
  51. folder, you should create one using the desktop or a file maintenance
  52. tool such as MaxiFile. 
  53.  
  54. Copy CAPTHOOK.PRG into your AUTO folder.  The programs in your AUTO
  55. folder run when you boot up your computer.  The order in which AUTO
  56. programs are executed may be important, depending on the program.  This
  57. execution order is determined by the order in which they are internally
  58. stored in your AUTO folder directory and may not have any correlation
  59. between their alphabetical order or even the order in which you copy
  60. them into the AUTO folder (dependent upon whether some programs have
  61. been deleted). 
  62.  
  63. Although CAPTHOOK.PRG can be placed at any execution point in your AUTO
  64. folder, its placement will affect how it interacts with your programs. 
  65. This is explained in more detail below (AUTO folder placement), but in
  66. general it's best for Captain Hook to run before any other programs
  67. which grab vectors. 
  68.  
  69. Upon copying CAPTHOOK.PRG into your AUTO folder, it will probably become
  70. the last program in the execution order.  The easiest way to rearrange
  71. the order of your AUTO programs is with the Auto Organizer program in
  72. the CodeHead Utilities package.  If you don't have Auto Organizer or any
  73. other method of changing the execution order, you should copy all of
  74. your AUTO programs to another location (or simply rename AUTO and create
  75. another AUTO folder if you have that capability) and copy the other
  76. programs back into your AUTO folder in the order you want them to run. 
  77.  
  78. After installing CAPTHOOK.PRG in your AUTO folder, you'll need to create
  79. and install a CAPTHOOK.DAT file.  This is explained below (The Captain
  80. Hook DAT File).  CAPTHOOK.DAT must be located in the root directory of
  81. your boot drive.  This will usually be drive C if you use a hard drive
  82. or drive A if you are a floppy disk user. 
  83.  
  84. NOTE: If you are going to be installing Captain Hook from anywhere other
  85. than the AUTO folder, CAPTHOOK.DAT should be in the _same_ directory as
  86. CAPTHOOK.PRG. 
  87.  
  88.  
  89. How it works
  90. ------------
  91.  
  92. Captain Hook deals with the Atari's system vectors.  When you install a
  93. resident program or accessory in your system, it may intercept one or
  94. more system vectors.  A vector is something that points to another
  95. location.  This pointing allows programs to redirect the flow of control
  96. in your computer and jump in at the appropriate time to provide some
  97. (hopefully) useful function.  Many system vectors are also referred to
  98. as interrupts since it is their function to interrupt the operation of
  99. the computer for various tasks. 
  100.  
  101. For an example, let's examine CodeKeys, the Macro Tool from CodeHead
  102. Software.  CodeKeys examines the keys that you press to determine
  103. whether it should intercede with a macro.  When you press a key on your
  104. keyboard an electrical pulse is sent to the master controller of
  105. operations in your computer (the Central Processing Unit, or CPU). 
  106.  
  107. This causes the CPU to "hold everything" and go see what the keyboard
  108. wants and it does this by looking at the keyboard vector.  This is a
  109. location in memory containing an address.  The address tells the CPU
  110. where to go to find the one in charge of handling the keyboard stuff. 
  111. If nothing is installed in your computer, this address will point into
  112. the ROMs and the CPU will go "knocking on the door" at that address. 
  113.  
  114. Returning to our CodeKeys example, CodeKeys runs in the AUTO folder and
  115. installs itself in the keyboard vector.  It does this by saving the
  116. address that is currently in the vector and replacing it with its own
  117. address.  Now when a key (for example, Control-A) is pressed, the CPU
  118. goes knocking on CodeKeys' door and says, "I have a letter here for
  119. Control-A.  Will you sign?".  CodeKeys looks in its notebook, determines
  120. whether it should handle it and either says, "Yes, I'll take it", or
  121. "No, that should be forwarded to:" (supplying the address that was
  122. previously in the keyboard interrupt). 
  123.  
  124. I know this is getting complicated but we're almost done.  As other
  125. programs also install themselves in the keyboard interrupt, each one
  126. saves the address that is there and replaces it with its own.  This
  127. causes the flow of control to pass through each program whenever a key
  128. is pressed.  When the CPU comes knocking, it may have to go to a number
  129. of different doors where nobody wants to sign for the letter before
  130. finding someone who'll take the responsibility. 
  131.  
  132. In fact, on the Atari, the same interrupt is used for keyboard, mouse,
  133. MIDI, and joystick.  This creates a real bottleneck when a lot of
  134. programs are installed, or even just one program that takes a lot of
  135. time to decide he doesn't want the letter or is simply very slow signing
  136. his name. 
  137.  
  138. This is why many MIDI programs have a hard time living with resident
  139. programs.  MIDI data enter the MIDI IN port at a high rate of speed. 
  140. Each byte of data that comes in must be handled before the next one
  141. arrives or it will be lost.  Each time a byte arrives at the MIDI IN
  142. port, an interrupt is generated and the CPU "goes knocking".  If the CPU
  143. can't arrive at the door of the guy who's handling the MIDI data and get
  144. back to the main station before another MIDI byte comes in, that data
  145. will be lost. 
  146.  
  147. This is where Captain Hook comes in.  When it installs, it takes note of
  148. all of the important vector addresses as they currently exist and saves
  149. them in its notebook.  This is why the order of execution is important
  150. because Captain Hook will be saving the currently installed vectors and
  151. will not be able to bypass any resident programs which are already
  152. installed. 
  153.  
  154.  
  155. The Captain Hook DAT file
  156. -------------------------
  157.  
  158. Once installed, Captain Hook waits for you to run programs.  Every time
  159. you run one of the programs listed in your CAPTHOOK.DAT file, it will
  160. replace any of the vectors you've listed for that program with the
  161. vectors it has stored from its initialization.  This allows you to
  162. effectively bypass or cut-out any programs which have intercepted those
  163. vectors between the time Captain Hook was installed and the time you run
  164. a program listed in CAPTHOOK.DAT. 
  165.  
  166. CAPTHOOK.DAT is simply an ASCII text file.  You can use any text editor
  167. or most any word processor to create it.  The requirements are as
  168. follows: 
  169.  
  170.  1.  The first four characters of the file must be "HOOK".
  171.  2.  It cannot be longer than 4096 bytes.
  172.  3.  Up to 32 programs can be listed.
  173.  4.  Each program must be at the beginning of its own line, followed by
  174.      one or more spaces and the vector codes for that program.
  175.  6.  Vector codes (listed below) are single characters denoting vectors
  176.      to be restored by Captain Hook.
  177.  5.  Comments may be placed in lines beginning with a semi-colon (;).
  178.  6.  Lines must end with a carriage return (ASCII 13).
  179.  7.  Blank lines are allowed and are ignored.
  180.  
  181.  Vector codes:
  182.  
  183.    A = line A              Rarely used
  184.    F = line F              Almost never used
  185.    1 = trap #1             Used by GEMDOS
  186.    2 = trap #2             Used by GEM, GDOS, alternate file selectors,
  187.                              screen accelerators
  188.    3 = trap #13            Used by BIOS, spoolers
  189.    4 = trap #14            Used by XBIOS
  190.    T = 200Hz interrupt     Various uses including Spectrum 512
  191.    K = kb/MIDI interrupt   Used by some programs providing "hot keys",
  192.                              such as CodeKeys
  193.    m = TOS mouse vec       Almost never used
  194.    I = ikbdsys vec         Used by many programs with "hot keys" such as
  195.                              HotWire, PinHead, PopIt, HotSaver, and Funk
  196.                              Alert
  197.    V = vbl (plus queue list) Used by many and varied programs
  198.    M = GEM mouse vector    Used by mouse accelerators and other programs
  199.                              such as Little Green Selector and HotSaver
  200.    S = MIDI in/err/sys     Used by MIDI programs
  201.    B = remainder of KBDVBAS (KBerr/KBstat/clk_pack/joy_pack)
  202.                            May be used (?)
  203.  
  204. Example CAPTHOOK.DAT file:
  205.  
  206. ------------------------------
  207.  
  208. HOOK
  209.  
  210. BBS.TOS A3K
  211. CAL.PRG 2
  212. SMPTETRK.PRG KIS
  213.  
  214. ------------------------------
  215.  
  216. A sample CAPTHOOK.DAT file is included with this package, containing
  217. commented lines with all of the vector codes listed above.  This
  218. eliminates the need for you to remember all of the codes when you are
  219. making changes to your DAT file. 
  220.  
  221. Here are some of the popular resident programs and the interrupts they
  222. use.  This does not mean that you have to "hook" all of their vectors,
  223. but it might give you a better idea how they might be interacting with
  224. your programs.
  225.  
  226. PINHED18.PRG  1,V,I
  227. POOLFIX4.PRG  1
  228. CODE_RAM.PRG  I (only if piggy-backed or print spooler installed)
  229. CODEKEYS.PRG  1,4,V,T,K
  230. REGACC.PRG    1,2,3,I
  231. G+PLUS.PRG    1,2
  232. HOTSAVER.PRG  2,3,4,V,T,I,M
  233. LGSELECT.PRG  1,2,3
  234. HOTWIRE.PRG   1,2,3,4,V,T,I
  235. FUNKALRT.PRG  2,3,I
  236. SENTINEL.PRG  1
  237. TOS14FIX.PRG  4,F
  238.  
  239. Hooking trap #2 will bypass any alternate file selectors you have
  240. installed. 
  241.  
  242. NOTE: If you are "hooking" trap #2, it is sometimes a good idea to also
  243. hook the keyboard interrupt (I and/or K) or you may may get a crash. 
  244. One example is PopIt, which will crash if you've hooked '2' without 'I'
  245. and you type a PopIt hot key.
  246.  
  247.  
  248.  
  249. AUTO Folder Placement
  250. ---------------------
  251.  
  252. As mentioned earlier, Captain Hook will interact differently with your
  253. resident programs depending on where it is installed in your AUTO
  254. folder.  Any program that intercepts vectors BEFORE Captain Hook runs
  255. will be unaffected by Captain Hook's operation.  Let's say that you're
  256. using the SMPTE Track sequencer and you've found that you can use it
  257. just fine with one or two programs installed in the keyboard interrupt
  258. but you get MIDI overflow errors if you've installed too many. 
  259.  
  260. You've decided that you can get along without PopIt (which doesn't work
  261. in SMPTE Track anyway due to the way SMPTE Track handles accessories),
  262. Funk Alert, and the HotWire keyboard interrupts (for turning the clock
  263. on/off) but you couldn't live without CodeKeys.  You should arrange the
  264. order of execution of your AUTO programs like this:
  265.  
  266.  CODEKEYS.PRG
  267.  CAPTHOOK.PRG
  268.  FUNKALRT.PRG
  269.  HOTWIRE.PRG
  270.  REGACC.PRG  (for PopIt)
  271.  
  272. Now if you've got an entry for SMPTETRK.PRG in your CAPTHOOK.DAT file
  273. like that shown in the example above, Captain Hook will cut out all of
  274. those programs except CodeKeys (which installed before Captain Hook took
  275. its "snapshot" of system vectors) when you run SMPTE Track and you'll
  276. have the use of CodeKeys with no MIDI overflow errors.
  277.  
  278. Once you understand this concept, a little experimentation will allow
  279. you to tune up your system to make optimum use of your resources with
  280. the least amount of interference and program conflict.
  281.  
  282.  
  283. Using Captain Hook with MIDI Spy
  284. --------------------------------
  285.  
  286. I've built some special communications with Captain Hook directly into
  287. MIDI Spy, CodeHead's background MIDI recorder.  If you run MIDI Spy as a
  288. program, you should _not_ list it in your CAPTHOOK.DAT file. 
  289.  
  290. Since MIDI Spy will normally be used as an accessory and you might be
  291. recording MIDI data at any time due to its background ability, it
  292. requires a special technique to allow you to use all of your resident
  293. programs but still have no MIDI overflow problems.  To accomplish this,
  294. MIDI Spy talks directly to Captain Hook.  If it finds the Captain, MIDI
  295. Spy goes directly into the Captain's back door and grabs its vectors as
  296. soon as any MIDI information comes in the MIDI ports.  If more than a
  297. second goes by with no MIDI data coming in, MIDI Spy restores the
  298. current vectors.
  299.  
  300. This process will generally have no ill effects on your system, but it
  301. _is_ possible for some irregularities to result.  As long as you are not
  302. doing anything at your computer keyboard within one second of playing
  303. MIDI data, it shouldn't matter.  But if you are playing your MIDI
  304. keyboard while someone else is operating the computer, strange things
  305. may happen.  For instance, the right mouse button selection of files in
  306. Little Green Selector might not work.
  307.  
  308. If you find that the interaction between Captain Hook and MIDI Spy is
  309. getting in the way with the normal operation of your computer, you'll
  310. have to remove Captain Hook and get along without it.  If Captain Hook
  311. is not installed, MIDI Spy will not attempt any vector manipulation.
  312.  
  313.  
  314. Copyright stuff
  315. ---------------
  316.  
  317. CAPTHOOK.PRG, and this document are Copyright 1991 John Eidsvoog. 
  318. Captain Hook is free to all MIDI Spy owners.  If you do not own MIDI
  319. Spy, then Captain Hook is a shareware program.  The idea of shareware is
  320. that you may distribute Captain Hook freely to anyone (please, as much
  321. as possible).  This method of distribution saves money for you the user
  322. and me the developer by eliminating marketing, manufacturing, and
  323. production costs.  If you make use of Captain Hook and did not purchase
  324. MIDI Spy, you are expected to register yourself as a Captain Hook owner
  325. by sending a payment of $15 to:
  326.  
  327.                  John Eidsvoog
  328.                  P.O. Box 74090
  329.                  Los Angeles, CA 90004
  330.  
  331. This will register you as an owner of Captain Hook.  Please specify
  332. Captain Hook in your correspondence, and if you would like to receive
  333. acknowledgment of your registration, include a self-addressed stamped
  334. envelope. 
  335.  
  336. Those who have registered Captain Hook for $15 will be eligible for a
  337. $15 discount on a later purchase of MIDI Spy. 
  338.  
  339. Please note that Captain Hook is not a CodeHead Software product,
  340. although it is provided free with a CodeHead product, MIDI Spy.  All
  341. CodeHead Software products are commercial programs which must be
  342. purchased through normal commercial channels.  CodeHead Software has
  343. never and will never release any shareware programs. 
  344.  
  345. Neither this document file (CAPTHOOK.TXT) nor the program file
  346. (CAPTHOOK.PRG) may be altered in any way.  Copies of these files may not
  347. be sold, and this document may not be reprinted, without the express
  348. written permission of John Eidsvoog. 
  349.  
  350. I've tried to make Captain Hook as bug-free as possible.  Nevertheless,
  351. I cannot be responsible for any damages which may occur as a result of
  352. the use (or misuse) of Captain Hook. 
  353.  
  354. Thank you for your support. 
  355.  
  356.                       John Eidsvoog
  357.  
  358.  
  359. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  360.  
  361.  
  362.   Version numbers and suggested retail prices for CodeHead Software
  363.   products as of Friday, December 6, 1991 are:
  364.  
  365.       Product              Version       Price
  366.       -------              -------       -----
  367.  
  368.       CodeKeys.............. 1.3 .......$39.95
  369.       G+Plus................ 1.5 ....... 34.95
  370.       MultiDesk Deluxe...... 3.3 ....... 49.95
  371.       LookIt & PopIt........ 1.2/1.1 ... 39.95
  372.       MaxiFile.............. 3.0 ....... 44.95
  373.       HotWire............... 3.0 ....... 44.95
  374.       HotWire Plus...................... 69.95
  375.       MIDI Spy.............. 1.0 ....... 79.95
  376.       MIDIMAX............... 1.3 ....... 49.95
  377.       CodeHead Utilities.... Rel 4 ..... 34.95
  378.  
  379.       CodeHead GT Graphic Tools:
  380.  
  381.       Avant Vector (EPS)..................$545
  382.       Avant Plot.......................... 895
  383.       MegaPaint Professional........... .. 175
  384.       Genus Font Editor................... 175
  385.